__doc__ =   """ functions for creation of patches of entites
            """

from Neighbors import Neighbors
from Einput import einput
from Selection import indicate


# EntityMisc API:
#   def indicate(entity, selector, arranger, *args, **kwargs

def get_seeds(entities, level, selector, arranger, k, *args, **kwargs):
    """ Universal seed generator. Returns a list of residues.
    """
    ents = einput(entities, level)
    seeds = indicate(ents, selector, arranger, *args, **kwargs)
    return seeds[:k]

def get_patches(entities, seeds, level, method, ctype, limit, selector, arranger, k, *args, **kwargs):
    """ Universal patch generator. Returns a list of Holders.
    """
    nn = eval(method)(entities, level, ctype)
    patches = []
    for seed in seeds:
        neighbors = nn.get_neighbors(seed, limit, level)
        patch = indicate(neighbors, selector, arranger, *args, **kwargs)
        patch = einput(patch[:k], level)
        patches.append(patch)
    return patches

def patches_xtra(patches, xtra):
    """ Utility function to annotate entites with patch number.
        use it to display patches via BeQu.
    """
    for patch in patches:
        for entity in patch:
            entity.xtra[xtra] = patches.index(patch) + 1

def patches_add_extra(patches, xtra):
    """ Utility function to check patching frequency
    """
    for patch in patches:
        for entity in patch:
            try:
                entity.xtra[xtra] += 1
            except KeyError:
                entity.xtra[xtra] = 1

#EOF